This abstracts away our tracing channels consumption into a utility that:

• Activates a span for the tracing channel lifecycle
• Manages the span across the entire lifecycle
  • Sets errors on the error channel
  • Correctly ends the span at the correct timing whether the traced call is sync or async
• Allows span/error enrichment and overrides

This util can be consumed uniformly across all of our server-side runtimes, I will create a stacked PR that refactors our code to use it, showcasing Nitro, Redis, and Deno adoption of that util.

API

// activates, and manages span across the trace lifecycle
const binding = bindTracingChannelToSpan(
  dc.tracingChannel('whatever'),
  data => {
    return startInactiveSpan('spanName', {
      // attrs..
    });
  },
  {
    // How much of the lifecycle should be managed
    // - 'auto' means span ending/errors are managed with context propagation
    // - 'manual' nothing is managed, only the context propagation is applied
    lifecycle: 'auto',

    beforeSpanEnd: (span, data) => {
      // Enrich the span or execute any related logic
      // Doesn't run if `manual` lifecycle is selected
    },

    /**
     * captures errors on the `error` channel, DB instrumentations should turn it off porbably
     * doesn't have an effect if lifecycle is `manual`.
     */
    captureError: true,
  },
);

Lifecycle Management

After testing across several node releases (20 -> 26), I locked down the strategy that we can rely on to make this reliable and predictable.

1. always start at start lifecycle event, this is emitted always and is reliable.
2. Use error For capturing exceptions and setting error span status, always reliable.
3. When end is emitted:
   1. If error is present on the context object, end the span immediatly, there won’t be any async events coming up, the function threw in the sync part, so there is no async part to execute.
   2. If result is present on the context object, end the span immediately, there won’t be any async events coming up. The function returned in the sync part or is sync trace itself. Use in or hasOwnProperty , Do not use undefined checks as the function can return nothing.
   3. Otherwise NO-OP, there is an async lifecycle events coming up.
4. When asyncStart is emitted: Do nothing, this event has no value for us.
5. When asyncEnd is emitted: Just end the span.